home *** CD-ROM | disk | FTP | other *** search
/ Aminet 50 / Aminet 50 (2002)(GTI - Schatztruhe)[!][Aug 2002].iso / Aminet / util / libs / ttrender.lha / ttrender-3.1 / Developer / autodocs / ttrender.doc
Text File  |  2002-05-28  |  20KB  |  566 lines
  1. TABLE OF CONTENTS
  2.  
  3. ttrender.library/background
  4. ttrender.library/font_database
  5. ttrender.library/TT_GetFontAttrsTagList
  6. ttrender.library/TT_OpenFontTagList
  7. ttrender.library/TT_PutStr
  8. ttrender.library/TT_PutStrTagList
  9. ttrender.library/TT_PutUStr
  10. ttrender.library/TT_PutUStrTagList
  11. ttrender.library/TT_SetFont
  12. ttrender.library/TT_SetModesTagList
  13. ttrender.library/TT_StrWidth
  14. ttrender.library/TT_UStrWidth
  15. ttrender.library/background                       ttrender.library/background
  16.  
  17.  
  18.    PURPOSE
  19.  
  20.    The library is fast, AmigaOS friendly TrueType render engine. It has
  21.    nothing to do with Amiga outline font system. This system has a lot of
  22.    limitations which make it useless for high speed and quality text output.
  23.    If someone wants an integration of TrueType with AmigaOS bullet.library
  24.    like outline font system, should consider using ttf.library. This library
  25.    opens TrueType font by itself and renders high quality glyphs directly
  26.    into any RastPort.
  27.  
  28.    FREETYPE2 BASED
  29.  
  30.    The render engine of the library is based on FreeType2 project
  31.    (http://www.freetype.org). This version of ttrender.library uses 2.0.9
  32.    FreeType build.
  33.  
  34.    REQUIREMENTS
  35.  
  36.    The library requires at least CyberGraphX 3.x or Picasso96 2.x system. It
  37.    is possible that non-antialiased output will be possible on AGA machines
  38.    in the future.
  39.  
  40.    FEATURES
  41.  
  42.    The library expands FreeType functionality making usage of TrueType fonts
  43.    easy and comfortable. Below you can find key features:
  44.  
  45.    - renders whole strings (not single glyphs) with kerning.
  46.    - antialiasing to any (not neccesarily uniform color) background.
  47.    - system compatible output to any (including planar) RastPort.
  48.    - supports JAM1. JAM2, INVERSVID, COMPLEMENT RastPort modes.
  49.    - supports 8-bit to Unicode mapping with "ENV:ttfcodepage" table
  50.      compatible with ttf.library.
  51.    - allows for direct 16-bit Unicode string rendering.
  52.    - easy to use, taglist based API.
  53.    - efficient system-wide glyph cache system.
  54.  
  55.    CACHE SYSTEM
  56.  
  57.    The library uses my own (not that experimental FreeType one) cache system
  58.    speeding up strings rendering alot. The cache is system-wide, it means it
  59.    is common to every application using ttrender.library. Only used glyphs of
  60.    given font face are cached. If the library encounters cache miss, missing
  61.    glyph is loaded and rasterized on the fly. Cache system is totally
  62.    transparent to the library user, so there are no cache functions in the
  63.    library API. Cache uses one single Exec memory pool avoiding memory
  64.    fragmentation.
  65.  
  66. ttrender.library/font_database                 ttrender.library/font_database
  67.  
  68.    GENERAL INFORMATION
  69.  
  70.    'ttrender.database' is a plain text file (placed in 'ENV:' directory)
  71.    containing informations about TrueType fonts available in the system.
  72.    There is no tool (yet) to automatically generate it, the database have to
  73.    be written by hand. Every line contains one keyword followed by parameter
  74.    value. Name and value can be separated by space(s) or equality sign,
  75.    exactly the same as shell command parameters (to say more - database is
  76.    parsed by the same ReadArgs() system call as shell command parameters
  77.    are). Parameter values containing spaces should be quoted. Here are some
  78.    examples:
  79.  
  80.    FAMILY Tahoma
  81.    FAMILY=Times
  82.    FAMILY = "Times New Roman"
  83.    FAMILY "Weird Font"
  84.  
  85.    KEYWORDS
  86.  
  87.    FAMILY - defines the name used for font opening. All variants of the font
  88.    (italic, bold, black, heavy, light, demi etc.) will have the same family
  89.    name. Family names (and aliases described below) are case insensitive.
  90.  
  91.    ALIAS - defines another name for the same family. It generally has three
  92.    purposes:
  93.  
  94.    1. Similar names for the same font, like "Times", "TimesNewRoman" and
  95.    "Times New Roman".
  96.  
  97.    2. One replacement font for some very similar ones, for example
  98.    "Helvetica" and "Switzerland" can be aliased to "Arial".
  99.  
  100.    3. Generic names like "default", "serif", "sans-serif", "monospaced". An
  101.    application can request generic name without specific family name, or
  102.    generic font can be used as a fallback if given name can't be found in
  103.    the database. For example you can alias "monospaced" to "Courier", and an
  104.    application (be it CSS compatible HTML viewer) can request
  105.    'LucidaConsole, monospaced'. If there is no LucidaConsole font in the
  106.    system, Courier will be used. The same way you can alias any font to any
  107.    other, for example Times to Arial, this makes not much sense however.
  108.    'default' font can be used as a last resort.
  109.  
  110.    FILE - defines single TrueType font file and its attributes, which are:
  111.      FILE itself - defines a path to the font file. Font files can be placed
  112.        anywhere in the filesystem(s). There is no default value for the
  113.        attribute, it must be given explicitly.
  114.      WEIGHT - defines font weight in Cascading Style Sheets manner, where 0
  115.        means the lightest and 999 means the heaviest weight. 400 is typical
  116.        value for normal weight, 700 for bold. Default value is 400 (normal).
  117.      STYLE - "regular" or "italic" for italic and oblique faces. Default
  118.        value is "regular".
  119.      SMOOTHSMALL - controls antialiasing of small sizes. Any sizes smaller or
  120.        equal to SMOOTHSMALL will be antialiased. Note: can be overriden by
  121.        application. Default value is 9.
  122.      SMOOTHBIG - controls antialiasing of big sizes. Any sizes bigger or
  123.        equal to SMOOTHBIG will be antialiased. Note: can be overriden by
  124.        application. Default value is 18.
  125.  
  126.      Every FILE is automatically added to the nearest FAMILY defined above
  127.      in the database file. Every ALIAS or FILE placed before the first
  128.      FAMILY is rejected quietly.
  129.  
  130.    COMMENTS
  131.  
  132.    You can place any full-line comments in the file starting a line with
  133.    hash or semicolon. End-line comments are not supported.
  134.  
  135. ttrender.library/TT_GetFontAttrsTagListtrender.library/TT_GetFontAttrsTagList
  136.  
  137.    NAME
  138.        TT_GetFontAttrsTagList -- Gets current font attributes (V2).
  139.  
  140.    SYNOPSIS
  141.        count = TT_GetFontAttrsTagList (taglist)
  142.                                        A0
  143.  
  144.        ULONG TT_GetFontAttrsTagList (struct TagItem*);
  145.  
  146.        count = TT_GetFontAttrsTags (Tag1, ...)
  147.  
  148.        ULONG TT_GetFontAttrsTags (Tag, ...);
  149.  
  150.    FUNCTION
  151.        Gets current (set by last SetFont() call) font attributes (global
  152.        metrics mainly). The value of every attribute is written to an ULONG
  153.        pointed by ti_Data field of the TagItem. Here is a list of attributes:
  154.  
  155.        TTFA_Ascender - This is a distance (in pixels) between the baseline
  156.          and top elements of the font (typically these elements are accents
  157.          of capital letters). NOTE: many shareware TT fonts have wrong ascen-
  158.          der value.
  159.  
  160.        TTFA_Descender - This is a distance (in pixels) between the baseline
  161.          and bottom elements of the font (typically in letters 'p', 'q', 'g'
  162.          etc.). NOTE: many shareware TT fonts have wrong descender value.
  163.          Descender value is typically negative (as bottom elements usually
  164.          are placed below the baseline).
  165.  
  166.        NOTE: TTFA_Ascender and TTFA_Descender are guarranted to fulfill
  167.        following formula: ascender - descender = font height.
  168.  
  169.    INPUTS
  170.        taglist - the list of attributes.
  171.  
  172.    RESULT
  173.        counter - the count of recognized tags.
  174.  
  175.    NOTES
  176.  
  177.    BUGS
  178.  
  179.    SEE ALSO
  180.        TT_SetFont()
  181.  
  182. ttrender.library/TT_OpenFontTagList       ttrender.library/TT_OpenFontTagList
  183.  
  184.    NAME
  185.        TT_OpenFontTagList -- Opens TrueType font using font database. (V3)
  186.  
  187.    SYNOPSIS
  188.        success = TT_OpenFontTagList (taglist)
  189.                                      A0
  190.  
  191.        BOOL TT_OpenFontTagList (struct TagItem*);
  192.  
  193.        success = TT_OpenFontTags (Tag1, ...)
  194.  
  195.        BOOL TT_OpenFontTags (Tag, ...);
  196.  
  197.    FUNCTION
  198.        Finds and sets TrueType font from the font database best matching
  199.        attributes given. Every following call of
  200.        TT_PutStr[Tags/TagList]() or TT_PutUStr[Tags/TagList]() will use
  201.        this font and size.
  202.  
  203.    INPUTS
  204.        taglist - a list of tags containing requested font attributes.
  205.               Following tags are recognized:
  206.          TTFA_FamilyTable - NULL-terminated table of pointers to font family
  207.               names from the most desired to the last resort fallback. It is
  208.               intended for easy implementing things like HTML 'FONT FACE'
  209.               attribute. You can use real family names here, as well as
  210.               generic names: 'serif', 'sans-serif', 'monospaced', 'cursive',
  211.               'fantasy', and 'default', especially useful as a fallbacks.
  212.               Family names are case insensitive.
  213.               The default value for the tag is {"default", NULL};
  214.          TTFA_Size - font size in pixels defined as the distance between
  215.               baselines of two following text lines. The default value for
  216.               this tag is 14 pixels.
  217.          TTFA_Style - there are two styles defined:
  218.               TTFA_Style_Regular (default),
  219.               TTFA_Style_Italic.
  220.          TTFA_Weight - defined with Cascading Style Sheets manner as a
  221.               number from 0 (the lightest face) to 999 (the heaviest face).
  222.               You can use TTFA_Weight_Normal (equal to 400) and
  223.               TTFA_Weight_Bold (equal to 700) shortcuts. TTFA_Weight_Normal
  224.               is the default value.
  225.  
  226.  
  227.    RESULT
  228.        success - TRUE if the font has been opened successfully, FALSE
  229.                  otherwise. This function can fail for four reasons:
  230.                  1. There is no matching face in the database (NOTE: even
  231.                     'default' can fail if not defined in the database!)
  232.                  2. File not found or malformed.
  233.                  3. Zero font size.
  234.                  4. No memory for requested (too big?) size.
  235.  
  236.    NOTES
  237.  
  238.    BUGS
  239.  
  240.    SEE ALSO
  241.        TT_PutStr(), TT_PutUStr(), font_database
  242.  
  243. ttrender.library/TT_PutStr                         ttrender.library/TT_PutStr
  244.  
  245.    NAME
  246.        TT_PutStr -- Renders string into RastPort.
  247.  
  248.    SYNOPSIS
  249.        success = TT_PutStr (string)
  250.                             A0
  251.  
  252.        BOOL TT_PutStr (UBYTE*);
  253.  
  254.    FUNCTION
  255.        Renders the string using current ttrender.library settings, and
  256.        current RastPort settings (pen, drawmode). String is rendered at
  257.        current RastPort (x, y) position, where 'y' means position of font
  258.        baseline. String is converted to Unicode according to
  259.        "ENV:ttfcodepage" mapping table. If there is no mapping table,
  260.        ISO-8859-1 mapping is used which is equal to ECMA Latin1 Amiga
  261.        standard.
  262.  
  263.    INPUTS
  264.        string - NULL-terminated string to render to.
  265.  
  266.    RESULT
  267.        TRUE if the string has been rendered.
  268.  
  269.    EXAMPLE
  270.        /* write a text with pen 1 and transp. background at (100, 100) */
  271.        /* rendering is done to a system window                         */
  272.  
  273.        SetAPen(win->RPort, 1);
  274.        SetDrMd(win->RPort, JAM1);
  275.        Move(win->RPort, 100, 100);
  276.        TT_SetModesTags(TTA_Window, win);
  277.        TT_PutStr("some text");
  278.  
  279.    NOTES
  280.  
  281.    BUGS
  282.  
  283.    SEE ALSO
  284.        TT_PutStrTagList(), TT_SetModesTagList(), TT_PutUStr()
  285.  
  286. ttrender.library/TT_PutStrTagList           ttrender.library/TT_PutStrTagList
  287.  
  288.    NAME
  289.        TT_PutStrTagList -- Renders string into RastPort with local settings.
  290.  
  291.    SYNOPSIS
  292.        success = TT_PutStrTagList (string, taglist)
  293.                                    A0      A1
  294.  
  295.        BOOL TT_PutStrTagList (UBYTE*, struct TagItem*);
  296.  
  297.        success = TT_PutStrTags (string, Tag1, ...)
  298.  
  299.        BOOL TT_PutStrTags (UBYTE*, Tag, ...);
  300.  
  301.    FUNCTION
  302.        Renders the string allowing temporary override of current
  303.        ttrender.library settings, and current RastPort settings. Attributes
  304.        given in the taglist have local precedence over global
  305.        ttrender.library settings set by TT_SetModesTagList() call. Check
  306.        TT_SetModesTagList() docs for a list of tags.
  307.  
  308.    INPUTS
  309.        string - NULL-terminated string to render to.
  310.  
  311.        taglist - local attributes valid only in this function call.
  312.  
  313.    RESULT
  314.        TRUE if the string has been rendered.
  315.  
  316.    EXAMPLE
  317.  
  318.        /* Turn antialias mode on globally */
  319.  
  320.        TT_SetModesTags(TTA_Antialias, TRUE);
  321.  
  322.        TT_PutStr("some text");           /* this text will be antialiased */
  323.        TT_PutStrTags("another text",
  324.          TTA_Antialias, FALSE,           /* this text won't (locally      */
  325.          TAG_END);                       /* switched off)                 */
  326.        TT_PutStr("third text");          /* this text will be antialiased */
  327.  
  328.    NOTES
  329.  
  330.    BUGS
  331.  
  332.    SEE ALSO
  333.        TT_PutStr(), TT_SetModesTagList()
  334.  
  335. ttrender.library/TT_PutUStr                       ttrender.library/TT_PutUStr
  336.  
  337.    NAME
  338.        TT_PutUStr -- Renders Unicode string into RastPort.
  339.  
  340.    SYNOPSIS
  341.        success = TT_PutUStr (string)
  342.                              A0
  343.  
  344.        BOOL TT_PutUStr (UWORD*);
  345.  
  346.    FUNCTION
  347.        Renders the string using current ttrender.library (RastPort, ColorMap,
  348.        render mode), and RastPort settings (pen, drawmode). String is
  349.        rendered at current RastPort (x, y) position, where 'y' means position
  350.        of font baseline. String is an 16-bit Unicode one and should be
  351.        terminated with 16-bit zero.
  352.  
  353.    INPUTS
  354.        string - 16-bit Unicode NULL-terminated string to render to.
  355.  
  356.    RESULT
  357.        TRUE if the string has been rendered.
  358.  
  359.    BUGS
  360.  
  361.    SEE ALSO
  362.        TT_PutUStrTagList(), TT_SetModesTagList(), TT_PutStr()
  363.  
  364. ttrender.library/TT_PutUStrTagList         ttrender.library/TT_PutUStrTagList
  365.  
  366.    NAME
  367.        TT_PutUStrTagList -- Renders 16-bit Unicode string into RastPort with
  368.                            local settings.
  369.  
  370.    SYNOPSIS
  371.        success = TT_PutUStrTagList (string, taglist)
  372.                                    A0      A1
  373.  
  374.        BOOL TT_PutUStrTagList (UWORD*, struct TagItem*);
  375.  
  376.        success = TT_PutUStrTags (string, Tag1, ...)
  377.  
  378.        BOOL TT_PutUStrTags (UWORD*, Tag, ...);
  379.  
  380.    FUNCTION
  381.        Renders the 16-bit Unicode string allowing temporary override of
  382.        current ttrender.library settings, and current RastPort settings.
  383.        Attributes given in the taglist have local precedence over global
  384.        ttrender.library settings set by TT_SetModesTagList() call. Check
  385.        TT_SetModesTagList() docs for a list of tags.
  386.  
  387.    INPUTS
  388.        string - NULL-terminated 16-bit Unicode string to render to.
  389.  
  390.        taglist - local attributes valid only in this function call.
  391.  
  392.    RESULT
  393.        TRUE if the string has been rendered.
  394.  
  395.    NOTES
  396.  
  397.    BUGS
  398.  
  399.    SEE ALSO
  400.        TT_PutUStr(), TT_SetModesTagList()
  401.  
  402. ttrender.library/TT_SetFont                       ttrender.library/TT_SetFont
  403.  
  404.    NAME
  405.        TT_SetFont -- Opens TrueType font with given name and size.
  406.  
  407.    SYNOPSIS
  408.        success = TT_SetFont (name, size)
  409.                              A0    D0:16
  410.  
  411.        BOOL TT_SetFont (STRPTR, UWORD);
  412.  
  413.    FUNCTION
  414.        Opens TrueType font file and sets current font size in pixels. Every
  415.        following call to TT_PutStr[Tags/TagList]() or
  416.        TT_PutUStr[Tags/TagList]() will use this font and size.
  417.  
  418.    INPUTS
  419.        name - pointer to a NULL terminated string containing font name.
  420.               ".ttf" suffix will be added automatically. Search order is
  421.               defined as follows:
  422.               1. current directory
  423.                   "<name>.ttf"
  424.               2. PROGDIR:
  425.                   "PROGDIR:<name>.ttf"
  426.               3. "FONTS:_TrueType_Outlines" (by analogy to _Bullet_Outlines)
  427.                   "FONTS:_TrueType_Outlines/<name>.ttf"
  428.        size - screen size of the font in pixels (to be exact - it is the
  429.               distance between baselines of two following lines of text
  430.               expressed in pixels).
  431.  
  432.    RESULT
  433.        success - TRUE if the font has been opened successfully, FALSE
  434.                  otherwise. This function can fail for three reasons:
  435.                  1. File not found or malformed.
  436.                  2. Zero font size.
  437.                  3. No memory for requested (too big?) size.
  438.  
  439.    NOTES
  440.        This function is considered obsolete starting from release 3 of the
  441.        library, because it by-passes font database. Use TT_OpenFontTagList()
  442.        instead.
  443.  
  444.    BUGS
  445.  
  446.    SEE ALSO
  447.        TT_PutStr(), TT_PutUStr(), TT_OpenFontTagList()
  448.  
  449. ttrender.library/TT_SetModesTagList       ttrender.library/TT_SetModesTagList
  450.  
  451.    NAME
  452.        TT_SetModesTagList -- Sets global rendering settings.
  453.  
  454.    SYNOPSIS
  455.        count = TT_SetModesTagList (taglist)
  456.                                    A0
  457.  
  458.        ULONG TT_SetModesTagList (struct TagItem*);
  459.  
  460.        count = TT_SetModesTags (Tag1, ...)
  461.  
  462.        ULONG TT_SetModesTags (Tag, ...);
  463.  
  464.    FUNCTION
  465.        Sets global (per library opening) render engine settings. Every
  466.        following TT_PutStr() / TT_PutUStr() call will use these settings.
  467.        They can by overriden temporarily however, with TT_PutStrTagList() /
  468.        TT_PutUStrTagList() calls. Here is a list of attributes:
  469.  
  470.        TTA_RastPort - (struct RastPort*) - Destination RastPort for
  471.          rendering. The library will adhere to this RastPort settings like
  472.          draw mode, pens, current pen position.
  473.  
  474.        TTA_ColorMap - (struct ColorMap*) - ColorMap used to convert pen
  475.          number to RGB color value.
  476.  
  477.        TTA_Screen - (struct Screen*) - useful shortcut for TTA_RastPort and
  478.          TTA_ColorMap, automatically sets screen ColorMap and screen
  479.          RastPort.
  480.  
  481.        TTA_Window - (struct Window*) - useful shortcut for TTA_RastPort and
  482.          TTA_ColorMap, automatically sets window ColorMap and window
  483.          RastPort.
  484.  
  485.        TTA_Antialias - (BOOL) - controls antialiasing (on or off).
  486.  
  487.    INPUTS
  488.        taglist - the list of global attributes.
  489.  
  490.    RESULT
  491.        counter - the count of recognized tags.
  492.  
  493.    NOTES
  494.        TTA_RastPort and TTA_ColorMap attributes have precedence over
  495.        TTA_Screen and TTA_Window ones. It can be useful if one wants to use
  496.        window/screen ColorMap but separate RastPort. An example:
  497.  
  498.        TT_SetModesTags(TTA_Window, win, TTA_RastPort, my_rport, TAG_END);
  499.  
  500.        It will set window colormap and 'my_rport' as targets. Note that the
  501.        precedence is based on tag values, not on tags order. So ordering of
  502.        the tags is meaningless for the function.
  503.  
  504.    BUGS
  505.  
  506.    SEE ALSO
  507.        TT_PutStr(), TT_SetModesTagList()
  508.  
  509. ttrender.library/TT_StrWidth                     ttrender.library/TT_StrWidth
  510.  
  511.    NAME
  512.        TT_StrWidth -- Gets string width in pixels (V2).
  513.  
  514.    SYNOPSIS
  515.        width = TT_StrWidth(string)
  516.                            A0
  517.  
  518.        ULONG TT_StrWidth (UBYTE*);
  519.  
  520.    FUNCTION
  521.        Calculates the pixel width of given string written with current font.
  522.        Takes kerning into account. String will be mapped to Unicode using
  523.        "ENV:ttfcodepage" table (see TT_PutStr() docs).
  524.  
  525.    INPUTS
  526.        string - the width of this string will be calculated.
  527.  
  528.    RESULT
  529.        width - the width of the string in pixels.
  530.  
  531.    NOTES
  532.  
  533.    BUGS
  534.  
  535.    SEE ALSO
  536.        TT_PutStr(), TT_SetFont()
  537.  
  538. ttrender.library/TT_UStrWidth                   ttrender.library/TT_UStrWidth
  539.  
  540.    NAME
  541.        TT_UStrWidth -- Gets Unicode 16-bit string width in pixels (V2).
  542.  
  543.    SYNOPSIS
  544.        width = TT_UStrWidth(string)
  545.                             A0
  546.  
  547.        ULONG TT_UStrWidth (UWORD*);
  548.  
  549.    FUNCTION
  550.        Calculates the pixel width of given 16-bit Unicode string written
  551.        with current font. Takes kerning into account.
  552.  
  553.    INPUTS
  554.        string - the width of this 16-bit Unicode string will be calculated.
  555.  
  556.    RESULT
  557.        width - the width of the string in pixels.
  558.  
  559.    NOTES
  560.  
  561.    BUGS
  562.  
  563.    SEE ALSO
  564.        TT_PutUStr(), TT_SetFont()
  565.  
  566.